<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <link rel="stylesheet" type="text/css" href="style.css" />
    <title>Cygwin Packaging: .hint files</title>
  </head>

<body>
<!--#include virtual="navbar.html" -->
<div id="main">
<!--#include virtual="top.html" -->
<h1>Cygwin Packaging: .hint files</h1>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2>Contents</h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<ul class="compact">
  <li><a href="#pvr.hint"><tt>package-version-release.hint</tt> file</a></li>
  <li><a href="#advanced_pvr.hint"><tt>package-version-release.hint</tt> file (Advanced Options)</a></li>
  <li><a href="#override.hint"><tt>override.hint</tt> file</a></li>
  <li><a href="#setup.hint"><tt>setup.hint</tt> file</a></li>
</ul>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2><a id="pvr.hint"><tt>package-version-release.hint</tt> file</a></h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<p>Each package must be submitted with a file
called <tt>package-version-release.hint</tt>. This file is used for information
that cannot be inferred just from the context of the file name or package
name. Lines in <tt>package-version-release.hint</tt> will consist of one of the
following:</p>
<pre>
# <i>comment</i>
sdesc: <i>"some text"</i>
ldesc: <i>"some text"</i>
category: <i>name1[ name2...]</i>
requires: <i>package[ package...]</i>
external-source: <i>package</i>
message: <i>id</i> <i>"some text"</i>
test:
skip:
</pre>
<p class="center">
  <b>Note: Not all of the above lines are required. Please read the description
  below for further details on how to construct a package-version-release.hint
  file.</b>
</p>

<ul class="spaced">
  <li>
    <p>Use UTF-8 character encoding.</p>
  </li>

  <li>
    <p>Lines that begin with '#' are comments and are ignored.</p>
  </li>

  <li>
    <p>
      <tt>sdesc</tt> is a one line description of the package, enclosed in
      double-quotes.  This is the information that will be displayed when
      installing packages via setup.
    </p>

    <p>
      Please note that the package name should <em>not</em> be part of the
      description, e.g. this is incorrect:
    </p>

<pre>
sdesc:      "boffo: A whackamole simulation in ASCII art"
</pre>

    <p>
      This is correct:
    </p>

<pre>
sdesc:      "A whackamole simulation in ASCII art"
</pre>

    <p>
      <tt>sdesc</tt> is a mandatory line.
    </p>
  </li>

  <li>
    <p>
      <tt>ldesc</tt> is a more descriptive, multi-line description of the
      package, enclosed in double-quotes.  It is intended for future use. e.g.:
    </p>

<pre>
ldesc:    "A whackamole simulation in ASCII art.
Intended for use on VT100 terminals at BAUD rates 1200 and
above.  Uses arrow keys for positioning over moles.  Space
bar whacks the mole.
No actual moles will be harmed during execution of this game."
</pre>

    <p>
      Note that there is currently no method for escaping double-quotes, so
       there is no way to represent a double-quote embedded in
       the <tt>ldesc</tt>.
    </p>

  </li>

  <li>
    <p>
      The <tt>category</tt> line indicates the categories that this package
      belongs to. One package can belong to multiple categories. Multiple
      categories are separated by spaces.
    </p>

    <p>
      Do not enclose multiple category names within quotation marks.
    </p>

    <a id="categories"/>
    <p>
      Please do not invent a new category without checking with the cygwin-apps
      mailing list first. At the time of writing, the current categories are:
    </p>

    <div id="category-list">
      <p>Accessibility</p>
      <p>Admin</p>
      <p>Archive</p>
      <p>Audio</p>
      <p>Base</p>
      <p>Comm</p>
      <p>Database</p>
      <p>Devel</p>
      <p>Doc</p>
      <p>Editors</p>
      <p>Games</p>
      <p>GNOME</p>
      <p>Graphics</p>
      <p>Interpreters</p>
      <p>KDE</p>
      <p>Libs</p>
      <p>Lua</p>
      <p>LXDE</p>
      <p>Mail</p>
      <p>MATE</p>
      <p>Math</p>
      <p>Mingw</p>
      <p>Net</p>
      <p>Ocaml</p>
      <p>Office</p>
      <p>Perl</p>
      <p>PHP</p>
      <p>Publishing</p>
      <p>Python</p>
      <p>Ruby</p>
      <p>Scheme</p>
      <p>Science</p>
      <p>Shells</p>
      <p>Sugar</p>
      <p>System</p>
      <p>Tcl</p>
      <p>Text</p>
      <p>Utils</p>
      <p>video</p>
      <p>Web</p>
      <p>X11</p>
      <p>Xfce</p>
    </div>

    <p>
      As you can see, currently, all categories consist of only a single
      word. We don't anticipate that this will change anytime soon.
    </p>

    <p>
      <tt>category</tt> is a mandatory line.
    </p>
  </li>

  <li>
    <p>
      The <tt>requires</tt> line indicates the packages that this package relies
      on. If your package is dependent on a file provided by another package
      that other package should be included here. The requires field may be
      missing or empty if your package truly does not require any other package.
    </p>

    <p>
      A package can rely on multiple other packages. Hierarchical dependencies
      should work correctly, however, it is best to always include specific
      dependencies, i.e. don't drop '<tt>bar</tt>' from your dependency list if
      your package requires it, even if you are including '<tt>foo</tt>' which
      relies on '<tt>bar</tt>'.
    </p>

    <p>
      Conversely, do not include package dependencies of <em>dependent</em>
      packages in your dependency list. If you think that another package has an
      incorrect dependency list, send email to cygwin-apps noting that fact.
    </p>

    <p>
      Multiple packages are separated by spaces. Do not enclose multiple package
      names within quotation marks.
    </p>
  </li>
  <li>
    <p>
      The <tt>message</tt> line indicates text that will be displayed by the
      setup program when the package is installed.
    </p>
    <p>
      This should be used <i>extremely</i> sparingly, for example, if a 3rd
      party driver or service needs to be installed in Windows for the package
      to function.
    </p>
    <p>
      The id used should be derived from the package name. Currently, the text
      for a given id will be shown by setup exactly once, when the package is
      first installed, even if the text subsequently changes.
    </p>
  </li>

  <li>
    <p>
      <tt>test</tt> indicates this is a test package.  The highest version
      marked as a test package will be installed by setup, when use of test
      packages is selected.
    </p>
    <p>
      With the current setup implementation, it will also mean that it will be
      overlooked by most people during installation.
    </p>
    <p>
      It is not required that your package have a <tt>test</tt> version. Use of
      a <tt>test</tt> version of a package is at the discretion of the package
      maintainer.
    </p>
  </li>

  <li>
    <p>
      <tt>skip</tt> is obsolete.
    </p>

    <p>
      It was only useful for indicating directories which contain source-only
      packages, which are automatically recognized, irrespective of <tt>skip</tt>.
    </p>
  </li>
</ul>
<p>Here's an example of a complete <i>release/boffo/boffo-1.0-1.hint</i>:</p>
<pre>
category: Games Text
requires: libncurses6 cygwin
sdesc:    "A whackamole simulation in ASCII art"
ldesc:    "A whackamole simulation in ASCII art.
Intended for use on VT100 terminals at BAUD rates 1200 and
above.  Uses arrow keys for positioning over moles.  Space
bar whacks the mole.
No actual moles will be harmed during execution of this game."
</pre>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2><a id="advanced_pvr.hint"><tt>package-version-release.hint</tt> file (Advanced Options)</a></h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<p>The <tt>external-source</tt> line is used when multiple installation packages are generated from a single source package. For example, suppose the <tt>boffo</tt> package contains the executables and documentation for boffo, but there is also a shared library <tt>cygboffo-7.dll</tt> that might be used by other packages; say, the <tt>fobbo</tt> program. It would be nice to separate that <tt>cygboffo-7.dll</tt> shared library into a second installation package, so that users of the <tt>fobbo</tt> program can install <em>just</em> the library, and not the entire <tt>boffo</tt> package. However, all of the <tt>boffo</tt> executables and the DLL are generated from the same source. To support this usage, the <tt>boffo</tt> maintainer would create three package files:</p>
<ul class="compact">
  <li><tt>boffo-2.4.1-2.tar.xz</tt>: an installable package that contains all of the normal contents of <tt>boffo</tt> -- except for the shared library.</li>
  <li><tt>libboffo7-2.4.1-2.tar.xz</tt>: an installable package that contains only the shared library from <tt>boffo</tt></li>
  <li><tt>boffo-2.4.1-2-src.tar.xz</tt>: the source package for boffo.</li>
</ul>
<p>
  <tt>boffo-2.4.1-2.tar.xz</tt>, <tt>boffo-2.4.1-2-src.tar.xz</tt>, and <tt>boffo-2.4.1-2.hint</tt> would go into the <tt>release/boffo/</tt> subdirectory.
  <tt>libboffo7-2.4.1-2.tar.xz</tt>, and <tt>libboffo7-2.4.1-2.hint</tt> would go into a separate subdirectory, such as <tt>release/boffo/libboffo7/</tt>.
  The two <tt>.hint</tt> files would look something like this:</p>
<div>
  <table border="2">
    <tr>
      <td>
	<div class="center">
	  <tt>boffo-2.4.1-2.hint</tt>
	</div>
      </td>
      <td>
	<div class="center">
	  <tt>libboffo7-2.4.1-2.hint</tt>
	</div>
      </td>
    </tr>
    <tr>
      <td><tt>category: Games Text<br />
       requires: libboffo7 libncurses6 cygwin<br />
       sdesc: "A whackamole simulation in ASCII art"<br />
       ldesc: "A whackamole simulation in ASCII art. Intended for use on VT100 terminals at BAUD rates 1200 and above. Uses arrow keys for positioning over moles. Space bar whacks the mole.<br />
       <br />
       No actual moles will be harmed during execution of this game."</tt>
       </td>
      <td><tt>category: Games Text<br />
       requires: cygwin<br />
       <b>external-source: boffo</b><br />
       sdesc: "Runtime library for a whackamole simulation in ASCII art"<br />
       ldesc: "A whackamole simulation in ASCII art. Intended for use on VT100 terminals at BAUD rates 1200 and above. Uses arrow keys for positioning over moles. Space bar whacks the mole.<br />
       <br />
       No actual moles will be harmed during execution of this game."</tt>
       </td>
    </tr>
  </table>
</div>
<p>The setup.ini generated from these .hint files will include these lines (only relevant lines shown):</p>
<pre>
@ boffo
requires: libboffo7 libncurses6 cygwin
version: 2.4.1-2
install: release/boffo/boffo-2.4.1-2.tar.xz
source: release/boffo/boffo-2.4.1-2-src.tar.xz
@ libboffo7
requires: cygwin
version: 2.4.1-2
install: release/boffo/libboffo7/libboffo7-2.4.1-2.tar.xz
source: release/boffo/boffo-2.4.1-2-src.tar.xz
</pre>

<p>
  Note that both packages point to the same source tar file. Also, it is required
  that the versions match (i.e. libboffo7-5.2 can't point to boffo-1.4-src).
  The same logic is used to "match up" other versions with their external
  sources.
</p>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2><a id="override.hint"><tt>override.hint</tt> file</a></h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<p>
  An <tt>override.hint</tt> file may exist, for information not associated
  with a specific <i>version-release</i>.
</p>

<pre>
# <i>comment</i>
curr: <i>version</i>
test: <i>version</i>
prev: <i>version</i>
keep: <i>version</i>[ <i>version</i>...]
keep-count: <i>count</i>
keep-days: <i>days</i>
</pre>

<ul class="spaced">
  <li>
    <p>Lines that begin with '#' are comments and are ignored.</p>
  </li>

  <li>
    <p>
      The <tt>curr</tt> line indicates which version of that package should be
      normally installed by setup. Use this setting <em>only</em> if you need to
      circumvent the normal version ordering.
    </p>

    <p>
      By default, the highest version-release number is used for the current
      version of a package.
    </p>

    <p>
      Use of <tt>curr</tt> is usually not required. e.g. if you had previously
      released <tt>boffo-0.9-1</tt> and now have a new <tt>boffo-1.0-1</tt>,
      there is no need to use <tt>curr</tt> as <tt>1.0-1</tt> is greater
      than <tt>0.9-1</tt>.
    </p>

    <p>
      However, if you had discovered a serious error in the <tt>boffo-1.0</tt>
      release, and then decided that you want to drop back
      to <tt>boffo-0.9-1</tt>, you could include an entry like this:
    </p>

<pre>
curr: 0.9-1
</pre>

    <p>
      This usage should be rare, however.
    </p>
  </li>

  <li>
    <p>
      Any <tt>test</tt> line indicates which version of that package should be
      installed by setup, when use of test packages is selected.
    </p>
    <p>
      So, something like "<tt>test: 1.9-1</tt>" will cause setup to characterize
      the 1.9-1 version as a "test" package.
    </p>
    <p>
      This should be obsolescent to the use of <tt>test:</tt> lines
      in <tt>package-version-release.hint</tt>.
    </p>
  </li>

  <li>
    <p>
      <tt>prev</tt> is obsolete, as setup no longer supports explicitly
      installing <tt>prev</tt> versions, so it now just indicates that the
      package should also be retained, and thus is equivalent to <tt>keep</tt>.
    </p>
  </li>

  <li>
    <p>
      <tt>keep</tt>, <tt>keep-count</tt> and <tt>keep-days</tt> can be used to
      override the default package expiry settings, when old package versions
      are automatically removed.
    </p>

    <p>
      All package versions listed in any <tt>keep</tt> line are always kept.
    </p>

    <p>
      A <tt>keep-count</tt> line causes the highest <i>count</i> versions to be
      kept.
    </p>

    <p>
      A <tt>keep-days</tt> line causes the first version which is less
      than <i>days</i> days old, and all higher versions to be kept.
    </p>
  </li>

</ul>

<div class="background">
  <b class="rtop"><b class="r1"></b><b class="r2"></b><b class="r3"></b><b class="r4"></b></b>
  <h2><a id="setup.hint"><tt>setup.hint</tt> file</a></h2>
  <b class="rbottom"><b class="r4"></b><b class="r3"></b><b class="r2"></b><b class="r1"></b></b>
</div>

<p>
  A <tt>setup.hint</tt> which acts as a <tt>package-version-release.hint</tt>
  for all <i>version-release</i> and as a <tt>override.hint</tt> is also
  supported, for backwards compatibility.
</p>

</div>
</body>
</html>
